refactor(settings): standardize Constance env overrides to CONSTANCE_ prefix DEV-1976 by platreth · Pull Request #7230 · kobotoolbox/kpi

platreth · 2026-07-09T10:30:10Z

🔗 Related PRs

Part of a 3-repo Constance env-var standardization:

chore(env): rename KOBO_SUPPORT_EMAIL to CONSTANCE_SUPPORT_EMAIL DEV-1976 kobo-install#279 — same rename in the kobo-install env template
chore(env): rename KOBO_SUPPORT_EMAIL to CONSTANCE_SUPPORT_EMAIL DEV-1976 kobo-docker#373 — same rename in the kobo-docker default env file

Backward compatibility is preserved (see below), so these can land independently — the deploy-repo PRs simply complete the migration to the new names.

📣 Summary

Standardize all Constance override env vars on a single CONSTANCE_ prefix.

📖 Description

The env vars that override Constance defaults used three conventions (bare, KOBO_, CONSTANCE_). This unifies them on CONSTANCE_, matching the existing CONSTANCE_ASR_MT_GOOGLE_* precedent.

Renamed:

KOBO_SUPPORT_EMAIL → CONSTANCE_SUPPORT_EMAIL
KOBO_SUPPORT_URL → CONSTANCE_SUPPORT_URL
KOBO_ACADEMY_URL → CONSTANCE_ACADEMY_URL
KOBO_COMMUNITY_URL → CONSTANCE_COMMUNITY_URL
USAGE_LIMIT_ENFORCEMENT → CONSTANCE_USAGE_LIMIT_ENFORCEMENT (env fallback in base.py + pytest env in pyproject.toml)

Backward compatible: each override reads the new CONSTANCE_-prefixed variable and falls back to the deprecated name (KOBO_* / bare) when it's unset, emitting a DeprecationWarning so deployments know to migrate. Old env vars keep working — no hard break.

The fallback logic lives in a new constance_env helper in kobo/settings/utils.py, moved out of base.py along with dj_stripe_request_callback_method.

✅ Test plan

test_api_environment.py — both settings axes
usage-limit-enforcement tests (KPI submissions, OpenRosa, subsequences)
deprecated env var still read + DeprecationWarning fired

… prefix Rename Constance override env vars to a single CONSTANCE_ prefix: - KOBO_SUPPORT_EMAIL/URL, KOBO_ACADEMY_URL, KOBO_COMMUNITY_URL - USAGE_LIMIT_ENFORCEMENT (env fallback + pytest env) BREAKING: deployments setting the old names must rename them. No backward-compat fallback (matches the existing ASR_MT_GOOGLE_* precedent).

greptile-apps · 2026-07-09T10:55:33Z

Greptile Summary

This PR standardizes all Constance env-var overrides to the CONSTANCE_ prefix by introducing a constance_env() helper in a new kobo/settings/utils.py module, which reads the new key first and gracefully falls back to the deprecated KOBO_* / bare name while emitting a DeprecationWarning. The pyproject.toml pytest env entry is updated to match, and dj_stripe_request_callback_method is relocated to the same utils module.

constance_env() helper (new utils.py): resolves env vars with new-key priority → deprecated-key fallback → hardcoded default, with a DeprecationWarning if the deprecated key is still present.
base.py: five Constance entries (SUPPORT_EMAIL, SUPPORT_URL, ACADEMY_URL, COMMUNITY_URL, USAGE_LIMIT_ENFORCEMENT) migrated to constance_env(); now coupled to two companion PRs in kobo-install and kobo-docker.
pyproject.toml: pytest env entry renamed from USAGE_LIMIT_ENFORCEMENT to CONSTANCE_USAGE_LIMIT_ENFORCEMENT.

Confidence Score: 5/5

Safe to merge; the refactoring is additive — old env var names continue to work via the deprecation fallback, so no silent drops can occur from merging kpi alone.

The logic in constance_env is straightforward and correct: new key wins, deprecated key falls back, hardcoded default is the last resort. The only behavioral nuance is that the deprecation warning fires even when both keys coexist, which may be unexpected during a rolling migration but causes no wrong values. The pyproject.toml update is a direct one-line rename and matches the implementation. The companion-repo coupling is clearly documented.

No files require special attention; the three changed files are consistent with each other.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Django settings loading] --> B{constance_env called}
    B --> C{deprecated_key in os.environ?}
    C -- Yes --> D[Emit DeprecationWarning]
    C -- No --> E[No warning]
    D --> F[getter new_key, getter deprecated_key, default]
    E --> F
    F --> G{CONSTANCE_* var set?}
    G -- Yes --> H[Use CONSTANCE_* value]
    G -- No --> I{Deprecated var set?}
    I -- Yes --> J[Use deprecated var value]
    I -- No --> K[Use hardcoded default]
    H --> L[Set as Constance default]
    J --> L
    K --> L

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Django settings loading] --> B{constance_env called}
    B --> C{deprecated_key in os.environ?}
    C -- Yes --> D[Emit DeprecationWarning]
    C -- No --> E[No warning]
    D --> F[getter new_key, getter deprecated_key, default]
    E --> F
    F --> G{CONSTANCE_* var set?}
    G -- Yes --> H[Use CONSTANCE_* value]
    G -- No --> I{Deprecated var set?}
    I -- Yes --> J[Use deprecated var value]
    I -- No --> K[Use hardcoded default]
    H --> L[Set as Constance default]
    J --> L
    K --> L

_{Reviews (3): Last reviewed commit: "refactor(settings): move settings helper..." | Re-trigger Greptile}

noliveleger · 2026-07-09T12:33:43Z

        'in the user interface',
    ),
    'SUPPORT_EMAIL': (
-        env.str('KOBO_SUPPORT_EMAIL', env.str('DEFAULT_FROM_EMAIL', 'help@kobotoolbox.org')),


Let's not break the compatibility here.
Just read from the new variable but keep reading from the deprecated one too.

For any deprecated variable. Please log a Deprecation warning instance.
See

kpi/kobo/settings/base.py

Lines 2007 to 2014 in 39416ad

if not (MONGO_DB_URL := env.str('MONGO_DB_URL', False)):

# ToDo Remove all this block by the end of 2022.

# Update kobo-install accordingly

logging.warning(

'`MONGO_DB_URL` is not found. '

'`KPI_MONGO_HOST`, `KPI_MONGO_PORT`, `KPI_MONGO_NAME`, '

'`KPI_MONGO_USER`, `KPI_MONGO_PASS` '

'are deprecated and will not be supported anymore soon.'

Yes, that's way better! Done

… names Per review: read the CONSTANCE_-prefixed var but fall back to the deprecated name (KOBO_*/bare), emitting a DeprecationWarning when the old name is still set. Adds the _constance_env helper (matches the existing KPI_BROKER_URL -> CELERY_BROKER_URL deprecation idiom).

noliveleger

You should also update the PR description.
It does not match what's happening anymore 🙏

noliveleger · 2026-07-13T18:02:55Z

 # `django.conf.settings.THE_SETTING`

+
+def _constance_env(getter, new_key, deprecated_key, default):


Would you mind to create an utility file where this could be moved out the settings files.
You can also move other helpers present in that file (e.g.: dj_stripe_request_callback_method)

Done in 078be15 — moved constance_env (renamed from _constance_env) and dj_stripe_request_callback_method into kobo/settings/utils.py. Also updated the PR description to match the current backward-compatible approach.

…EV-1976

noliveleger

LGTM

This was referenced Jul 9, 2026

chore(env): rename KOBO_SUPPORT_EMAIL to CONSTANCE_SUPPORT_EMAIL DEV-1976 kobotoolbox/kobo-install#279

Merged

chore(env): rename KOBO_SUPPORT_EMAIL to CONSTANCE_SUPPORT_EMAIL DEV-1976 kobotoolbox/kobo-docker#373

Open

platreth marked this pull request as ready for review July 9, 2026 10:48

platreth requested review from jnm and noliveleger as code owners July 9, 2026 10:48

noliveleger requested changes Jul 9, 2026

View reviewed changes

platreth self-assigned this Jul 9, 2026

platreth removed the request for review from jnm July 9, 2026 14:01

platreth added the Back end label Jul 9, 2026

platreth requested a review from noliveleger July 9, 2026 15:26

noliveleger requested changes Jul 13, 2026

View reviewed changes

refactor(settings): move settings helpers to kobo/settings/utils.py D…

078be15

…EV-1976

noliveleger approved these changes Jul 14, 2026

View reviewed changes

platreth merged commit 08edb9f into main Jul 15, 2026
18 checks passed

platreth deleted the hugo/dev-1976-constance-env-prefix branch July 15, 2026 08:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor(settings): standardize Constance env overrides to CONSTANCE_ prefix DEV-1976#7230

refactor(settings): standardize Constance env overrides to CONSTANCE_ prefix DEV-1976#7230
platreth merged 3 commits into
mainfrom
hugo/dev-1976-constance-env-prefix

platreth commented Jul 9, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Jul 9, 2026 •

edited

Loading

Greptile Summary

Confidence Score: 5/5

Flowchart

Uh oh!

noliveleger Jul 9, 2026

Uh oh!

platreth Jul 9, 2026

Uh oh!

noliveleger left a comment

Uh oh!

noliveleger Jul 13, 2026

Uh oh!

platreth Jul 14, 2026

Uh oh!

noliveleger left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	if not (MONGO_DB_URL := env.str('MONGO_DB_URL', False)):
	# ToDo Remove all this block by the end of 2022.
	# Update kobo-install accordingly
	logging.warning(
	'`MONGO_DB_URL` is not found. '
	'`KPI_MONGO_HOST`, `KPI_MONGO_PORT`, `KPI_MONGO_NAME`, '
	'`KPI_MONGO_USER`, `KPI_MONGO_PASS` '
	'are deprecated and will not be supported anymore soon.'

		# `django.conf.settings.THE_SETTING`


		def _constance_env(getter, new_key, deprecated_key, default):

Uh oh!

Uh oh!

Conversation

platreth commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Related PRs

📣 Summary

📖 Description

✅ Test plan

Uh oh!

greptile-apps Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Flowchart

Uh oh!

noliveleger Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

platreth Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

noliveleger left a comment

Choose a reason for hiding this comment

Uh oh!

noliveleger Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

platreth Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

noliveleger left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

platreth commented Jul 9, 2026 •

edited

Loading

greptile-apps Bot commented Jul 9, 2026 •

edited

Loading